Skip to main content

Leaderboard Functions

To manage leaderboards, use the functions exported by the Leaderboard adapter.

Importing the adapter​

To use the functions of the Leaderboard adapter, import it as shown:
import { leaderboardAdapter } from 'epicenter-libs';

The leaderboardAdapter namespace exports functions that make calls to the Leaderboard API.

learn more

For descriptions of the objects used by the Leaderboard adapter functions, read Leaderboard entities.

Retrieve​

These functions return leaderboard data.

Get leaderboard​

To retrieve entries from a leaderboard, use the list() function.

learn more

For reference on search filters, read Filter and sort syntax.

warning

The results are not paginated.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The list() function:

  • Constructs a GET request to the /leaderboard/{scopeBoundary}/{scopeKey}/{collection} endpoint.
  • Gathers leaderboard entries that match the specified filters, sort options, and scope.
  • Designed for lightweight queries where no single "leader" is determined.
  • Returns a list of leaderboard objects.
Function signature
export async function list(
    collection: string,
    scope: GenericScope,
    searchOptions: GenericSearchOptions,
    optionals: RoutingOptions = {}
): Promise<Leaderboard[]>

Parameters​

  • collection (string): Name of the leaderboard to retrieve entries from.
  • scope (GenericScope): Defines the scope for the leaderboard query.
  • searchOptions (GenericSearchOptions): Filter and search options. No pagination.
  • optionals (RoutingOptions, optional): Additional routing options.

Return value​

A promise that resolves to a list of Leaderboard objects.

Usage example​

import { leaderboardAdapter } from 'epicenter-libs';

const leaderboard = await leaderboardAdapter.list('myLeaderboard', scope, {
    filter: [
        'tag.role=doctor',    // look for leaderboard entries tagged with role=doctor
        'score.total>0'       // where the users scored a total higher than 0
    ],
    sort: ['+score.total'],   // sort results by 'total' in ascending order
    first: 0,
    max: 20                   // retrieve only the first 20 entries
});

Count leaderboard entries​

To retrieve the number of entries in a leaderboard collection, use the getCount() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The getCount() function:

  • Constructs a GET request to the /leaderboard/count/{scopeBoundary}/{scopeKey}/{collection} endpoint.
  • Applies optional filters to narrow the count to specific conditions.
  • Returns the total number of leaderboard entries that match the given criteria.
learn more

For reference on search filters, read Filter and sort syntax.

Function signature
export async function getCount(
    collection: string,
    scope: GenericScope,
    searchOptions: GenericSearchOptions,
    optionals: RoutingOptions = {}
): Promise<number>

Parameters​

  • collection (string): Name of the leaderboard collection.
  • scope (GenericScope): Defines the scope for the leaderboard count.
    • scope.scopeBoundary (string): The boundary for the scope (e.g., group, project, episode, or world).
    • scope.scopeKey (string): The key for the resource identified by scopeBoundary.
  • searchOptions (GenericSearchOptions): Provide filter and sort parameters here.
  • optionals (RoutingOptions, optional): Additional routing options.

Return value​

A promise that resolves to a number representing the count of leaderboard entries matching the filter.

Usage example​

import { leaderboardAdapter } from 'epicenter-libs';

const leaderboard = await leaderboardAdapter.getCount('myLeaderboard', scope, {
    filter: [
        'tag.role=doctor',    // look for leaderboard entries tagged with role=doctor
        'score.total>0'       // where the users scored a total higher than 0
    ]
});

Create and update​

To create a new leaderboard or update entries in an existing leaderboard, use the update() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The update() function:

  • Constructs a POST request to the /leaderboard endpoint.
  • Creates the leaderboard if it doesn't already exist.
  • Assigns the provided scope to the leaderboard. If a user key is not provided, the one from the active session is used.
  • Adds a new entry to the leaderboard.
  • Accepts multiple scores and optional tags to facilitate searching for scores.
  • Returns the created leaderboard entry object.
Function signature
export async function update(
    collection: string,
    scope: { userKey?: string } & GenericScope,
    scores: Score[],
    optionals: {
        tags?: Tag[],
        allowChannel?: boolean,
    } & RoutingOptions = {}
): Promise<Leaderboard>

Parameters​

  • collection (string): Name of the leaderboard to update.
  • scope ({ userKey?: string } & GenericScope): Provide a user-specific scope for the leaderboard entry.
    • scope.scopeBoundary (string): The scope boundary.
    • scope.scopeKey (string): The scope key.
    • scope.userKey (string, optional): The user associated with this entry. Defaults to the current session user if omitted.
  • scores (Score[]): A list of score objects.
    • name (string): The name of the score (e.g., "total", "extraCredit"). Must be unique for the user-specific scope.
    • quantity (number): The numerical value for the score.
  • optionals ({ tags?: Tag[], allowChannel?: boolean } & RoutingOptions, optional):
    • tags (Tag[], optional): Tags to further scope or categorize the leaderboard entry.
    • allowChannel (boolean, optional): Enables push updates to CometD channels.
    • RoutingOptions: Additional routing options for the request.

Return value​

A promise that resolves to a Leaderboard object.

Usage example​

import { leaderboardAdapter } from 'epicenter-libs';

const leaderboard = await leaderboardAdapter.update(
    'class-23-leaderboard',
    {
        scopeBoundary: SCOPE_BOUNDARY.GROUP,
        scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461',
    },
    [
        { name: 'total', quantity: 20 },
        { name: 'extraCredit', quantity: 2 },
    ],
    {
        tags: [{ label: 'role', content: 'doctor' }]
    }
);